Mosquitto Client Certificate Authoritiy Management

Premium

There are multiple ways of authenticating clients. The most common way is using the dynamic-security plugin and creating client accounts with a username password approach. An added security layer for authentication is the usage of client certificates. These can be used in addition or as an alternative to the username password authentication.

Client certificates are a digital certificate, which is used by a connecting client to authenticate at a server. The server approves a connection, if the certificate can be validated by a stored client certificate authority. This setting is configured in the mosquitto.conf file. To allow a deployment of CAs via another entity, this plugin provides a Mosquitto control API which manages CA certificates for certificate based authentication/validation.

The topic of the plugins control API is $CONTROL/certificate-management/v1. Currently, supported commands offered by the API are insertCACertificate, which can be used to extend the existing Certificate Authority (CA) Chain or just the Root CA by an additional signing/validating certificate. To get rid of a previously added CA cert, the deleteCACertificate command can be used.

Plugin configuration

To enable the plugin it must be loaded into the broker with, by adding the following to your mosquitto.conf:

plugin /usr/lib/cedalo_certificate_management.so

In addition to enable the brokers internal $CONTROL/broker/v1 API we need to add:

enable_control_api true

This is required to determine the listeners identifier, where the changes should be applied to.

A sample broker configuration could look like:

listener 1883 127.0.0.1 # listener 1 to manage the CA certificates (local connection only)

listener 8883 # listener 2 to be managed, accepting the client connections
certfile server.crt
keyfile server.key
capath ca_path
require_certificate true

allow_anonymous true
enable_control_api true

plugin /usr/lib/cedalo_certificate_management.so

The path of the capath configuration should contain at least a root CA cert.

Note: The cafile configuration with a single PEM file containing the CA chain is currently not supported for this command.

To add a new CA certificate to the running broker instance you can either use mosquitto_ctrl or initiate a request-response API call.

To learn more about the API check out our API documentation. If you are not into APIs and are looking for a UI to handle this functionality, you can use the Mosquitto Management Center to upload and deploy CAs.